feat(routes): include generated route declarations by default (AB4834); reject duplicated framework plugins in tools.rsbuild (AB4724) - #497

Two small improvements from the agent-bundle ↔ TanStack / React-Router cross-reference.

Matrix rows

• Row 7, suggestion 3 — typed routes on by default. feat(test): type renderRoute ids, inputs, and results from the generated route registration #456 added TanStack-style typed routes (.agent-bundle/routes.d.ts augments Register in @agent-bundle/runtime), but the file only took effect when a project's tsconfig happened to include it; the scaffold and several examples did not, so renderRoute silently degraded to string / unknown. TanStack keeps routeTree.gen.ts inside src/ so it is always in the program.
• Row 14, suggestion 4 — plugin-order / collision diagnostic. Rsbuild's plugin manager appends every plugin it is handed and never dedupes by name, and both composition paths concatenate plugins arrays, so tools.rsbuild.plugins: [pluginReact()] silently doubled the framework's own @rsbuild/plugin-react. rsbuild-plugin-react-router ships validation/validate-plugin-order.ts for exactly this.

Item 1 — .agent-bundle/routes.d.ts in the program by default (AB4834)

• packages/create-agent-bundle/templates/{minimal,mcp-server,cli-tool}/tsconfig.json and every example tsconfig (examples/{audiobook-curator,host-test,mcp-app,rsc-agent-runtime,worktree-proximity}/tsconfig.json; mcp-app gained its tsconfig in chore(examples): drop stray host-test probe note; add mcp-app typecheck and make it pass --strict #491 and compiles no route graph, so the entry is inert there until it does) list ".agent-bundle/routes.d.ts" in include. A literal entry, because TypeScript's **/* never descends into dot-directories; include rather than files, because an include entry is inert until the first build publishes the file while a missing files entry is a tsc error. The file stays gitignored (verified for every example and asserted for every template).
• New packages/agent-bundle/src/routes/typegen-program.ts: routeTypesProgramDiagnostics(root) resolves the root tsconfig.json program the way tsc -p does (ts.parseJsonConfigFileContent over ts.sys: extends, files, include, exclude, plus one level of project references for a solution-style root) and reports AB4834 (warning) when the published declaration is not among its root files. No root tsconfig, no published declaration (route-free and provider-free), or an unparsable tsconfig → nothing (no program to be missing from, or tsc reports the parse failure itself).
• Wired in src/dev/project-service.ts#prepare right after writeRouteTypes, for command === 'validate' only — the same surface every other non-error source nudge uses, and the placement means the check judges the file that was just published against the real file system instead of re-implementing TypeScript's glob semantics.
• examples/audiobook-curator/tests/route-unit/context.test.ts: with the declaration in the program, the degraded-path test's providers: {} became a compile error (the generated augmentation makes library required — exactly the silent gap this row is about). The deliberate contract violation is now an explicit cast with a comment.
• examples/worktree-proximity/tests/route-unit/routes.test.ts: same mechanism, other direction — the example gained an agentTopology provider on main (chore(examples): use built-in framework surface over hand-rolled setup #473), and with the declaration in the program an explicit providers map that only carried gitWorktree no longer compiles (CI Examples check on 3fe4c39). The fixture now carries every declared key through one providers(root) helper; the topology factory is pure and returns the same honest-unavailable value the harness mounts.

Item 2 — framework-owned plugin collision (AB4724)

• New packages/agent-bundle/src/build/framework-plugins.ts: the set of Rsbuild plugins the framework registers (rsbuild:react → @rsbuild/plugin-react, from rslib.ts for every synthesized entry and mcp-apps.ts for React-syntax views) and frameworkOwnedPluginCollisions(plugins), which flattens nested arrays the way Rsbuild does, skips false/null/undefined holes, and matches plugin objects by name. Promise-form plugins carry no name until awaited and are not inspected (documented).
• src/config/validate.ts#validateTools emits AB4724 (error) naming the plugin and its package, with the fix. Error at validate time rather than a build-time warning because that is what the existing scheme does for tools config problems (AB4720–AB4723 are validate-time errors from the same function): it is a config problem with one deterministic fix, reported once at the source before any bundler runs, and it gates validate, build, inspect, and dev alike through the existing hasErrors(sourceDiagnostics) path. Verified against @rsbuild/core 2.2.1's createPluginManager.addPlugins (plain push, no name check).
• The names are literals so the validator never loads a bundler plugin to read a string; tests/framework-plugins.test.ts pins each literal to pluginReact().name.

Docs

docs/diagnostics.md (new "bundler escape hatch (AB4720–AB4724)" section, AB4834 row and prose in the route-graph section, family table), docs/framework-mode.md, docs/entry-conventions.md, packages/agent-bundle/README.md, and en+zh guide/authoring/package-entries, guide/development/index, guide/development/testing, reference/configuration. The generated diagnostics reference page follows docs/diagnostics.md.

Tests

• New tests/route-types-program.test.ts (5 tests through validate() / inspect() on temp projects: warning shape; silent for explicit include, .agent-bundle/**/*, and files; extends and references followed; **/* alone still warns; no tsconfig / no routes / broken tsconfig silent; validate-only).
• New tests/framework-plugins.test.ts (name drift check, nested/hole flattening, unrelated/deferred plugins).
• tests/package-conventions.test.ts: duplicate pluginReact() → one AB4724; unrelated user plugins → no diagnostic.
• create-agent-bundle/tests/scaffold.test.ts: every template's tsconfig include carries the entry and .gitignore ignores .agent-bundle/.
• Existing route-register-typegen.test.ts and provider-typegen.test.ts pass unchanged.

Local: pnpm build, pnpm lint, pnpm typecheck, pnpm test:unit (3117 passed), pnpm --filter './examples/*' check (all seven examples: validate → build → typecheck → tests), scaffold-packed.e2e + scaffold-packed-matrix.e2e under the release packed pool (4/4; each scaffolded template runs its own check, so tsc now sees the generated declaration), pnpm docs:site:build (parity and dead-link checks green).

Changeset

.changeset/typed-routes-by-default-and-plugin-collision.md — patch for agent-bundle and create-agent-bundle.

Review status

Rebased onto main three times: after #487 (release-audit gate removed), after #491/#494/#495/#504, and after #501 (create-agent-bundle on Effect FileSystem/Path — the scaffold include test was ported to the it.effect / readJson style, the only conflict). The main docs-build fix this branch briefly carried was dropped in the last rebase because #507 landed the identical change. Per the working instructions for this PR, no comments are posted from this side; the review record lives here.

• chatgpt-codex-connector reviewed e664850 (PR opened) with one P1 finding: no .changeset/*.md in the commit. Addressed in the changeset commit (.changeset/typed-routes-by-default-and-plugin-collision.md, patch for agent-bundle and create-agent-bundle, summary ends (#497)); the Changeset present check is the machine confirmation.
• Last-reviewed head: e664850 (pre-rebase; its content is ae32e81 after the rebases). Unreviewed since then: the changeset (02f7cbe), the worktree-proximity fixture (3da15e8), and the mcp-app include + framework-plugins.ts doc comment pointing at refactor(build): one shared tools-hatch layering for every synthesized bundler config (xref row 13) #495's composeToolsLayers (5ec3361). No behavior change in packages/** since the reviewed commit; the scaffold test port is mechanical.